September 95 - Document Synchronization and Other Human Interface Issues
Document Synchronization and Other Human
Interface Issues
Mark H. Linton
One of the things the Finder does best is maintain the illusion that an icon and its
window represent a single object. Using the routines described in this article, your
application can help maintain that illusion. You can ensure that when the user renames
an open document, the change is reflected in the document window's title. You can also
gracefully handle problems that may arise if the document file is moved. Other
improvements that make your application's interface more consistent with the
Finder's include preventing a second window from opening when an open document's
icon is double-clicked and adding a pop-up navigation menu to the document window's
title bar.
To rename a folder or file in the Finder, you click the icon name, type a new name, and
press Return. For folders, if the window is open, the change is reflected right away in
the window's title bar. But for files, if the document is open in your application, its
window may not reflect the name change. Try this little experiment: Create a document
in your application and save it. Switch to the Finder, find your document, and change
its name. What did your application do? If it's like most applications, nothing
happened: the document window has the same name as before. Go ahead and try to use
Save As to give the file the same name you gave it in the Finder. You probably get an
error message. Now try to save the document under the original name. Do you still get
an error message? Quit your application and read on for a way out of this frustration.
The only convenient way for a user to rename a document is with the Finder. (The Save
As command doesn't rename a document; it creates a copy of the document with a new
name.) As you've just seen, name changes made in the Finder aren't automatically
reflected in an open document window. Another change that's often not picked up by the
application is when the user moves the document to a different folder. The code in this
article helps synchronize your application's documents with their corresponding files,
so that a document will respond to changes made outside the application to its file's
name or location.
This article also describes how to prevent a duplicate window from being opened if the
user opens an already open document in the Finder and how to add a pop-up menu to the
document title bar to help the user determine where the file is stored. All the code for
implementing these features is provided on this issue's CD, along with a sample
application that illustrates its use.
DOCUMENT SYNCHRONIZATION
should "match the window title to the filename." Specifically, when a user changes the
document name in the Finder, you should update all references to the title. The guide
also refers to the Macintosh Human Interface Guidelines,page 143, where it says, "The
document and its corresponding window name must match at all times.
When I first started looking at the problem of document synchronization, I assumed
that the animated example in the Electronic Guide to Macintosh Human Interface Design
was the way to go. In this animation, the application checks for a name change when it
receives a resume event. However, I became uncomfortable with this approach,
because it would cause a delay between the user's changing the name of the document in
the Finder and the application's updating the window title. Using a resume event relies
on a separate action by the user, namely, bringing the application to the foreground.
This seemed nonintuitive and didn't support the illusion that a window and its icon
represent a single object. Also, it's possible that with Apple events and AppleScript an
application could be launched, do some work, and quit without ever being frontmost --
that is, without ever receiving a resume event.
The truth is that these days, with multiple applications running at the same time, with
networked, shared disks everywhere, and with applications and scripts pulling the
puppet strings as often as users, a file's name or location may change at any time,
whether the application is in the foreground or the background. A script might move or
rename a file or, if the file is on a shared volume, another user on the network could
move or rename it or even put the file in the Trash -- all behind the application's
back. The only solution I found under the current system software was to regularly
look at the file to see if its name or location has changed. In other words, the
application has to poll for changes.
Polling is generally a bad idea, but there are cases when it's the only reasonable way to
accomplish a task, and this is one of them. However, I tried to keep the polling very
"lightweight" and low impact by using the following guidelines:
• An application shouldn't poll any more often than it absolutely needs to.
Waking up an application causes a context switch, and context switches take a
significant amount of time. Forcing the system to wake up an application every
few ticks just so that it can look for file changes would be a bad idea,
especially when the application is in the background. Instead, the application
should poll only when an event has already been received -- that is, when the
application is awake. Set your WaitNextEvent sleep time appropriately, and
wait at least a second or two between "peeks." (The Finder, for instance, polls
for disk changes every five seconds or so.)
• Avoid any polling that causes disk or network access; if at all possible,
examine only information that's in RAM on the local machine. Network access
in particular can be a real drain on performance.
The sample code follows this advice, doing everything it can to be unobtrusive. It polls
for file changes only once every second while in the foreground. In the background, the
application's WaitNextEvent sleep time is set to ten seconds, so it only wakes up --
and thus polls -- every ten seconds if nothing else is going on. To detect changes to
files, I chose to examine the volume modification date of the volume containing the file,
since this information is always available in local RAM, even for a shared volume. If
that date changes, I look deeper to see if the change is one I'm interested in. As you dip
into the code, you'll see the details.I use the file reference number to track files
because it survives changes in the name and parent directory. However, this requires
that the files be kept open. If you can't keep your files open, you might want to look at
John Norstad's excellent NewsWatcher application, which uses alias records to
synchronize files. NewsWatcher is on this issue's CD; its official source can be found
at ftp://ftp.acns.nwu.edu/pub/newswatcher/.*
Friendly as it is, this polling solution is appropriate only for the current system
software; future system software versions (such as Copland, the next generation of the
Mac OS) will provide a much better way to detect changes. Your application will be
able to subscribe to notification of changes that it's interested in. In fact, polling the
current file system structures will be unfriendly behavior under Copland, which will
have demand-paged virtual memory and a completely new file system. For this reason,
the sample code is designed to work only under System 7. You'll be able to easily
retrofit the code to run under Copland once the details of the correct way to detect file
changes have been worked out.
THE HEART OF THE MATTER
Every Macintosh programmer eventually comes to grips with how to keep track of all
the information associated with a document. I use a structure called a document list and
I have a set of routines that support it. The document list reverses some common
assumptions used by developers. Developers often use the window list to track their
windows and attach their document data to it, but this limits Apple's ability to redefine
the window list. My recommendation is to create a document list (almost identical to
the window list) containing the document data and attach the windows to it. In this way,
the actual structure of the window list is not a concern. You'll find my implementation
of the document list and its supporting routines on this issue's CD.
While the code presented here is specific to my implementation, you can easily
generalize it as needed. The code below shows how your application might call
DSSyncWindowsWithFiles, a routine that keeps your documents synchronized with the
Finder by checking for and handling changes made outside the application to file names
or locations. Call the routine from within your main event loop when you receive an
event (including null events). Note that error checking has been removed from the
code shown in the article, but it does appear on the CD.
while (!done) {
gotEvent = WaitNextEvent(everyEvent, &theEvent, gSleepTime,
theCursorRegion);
if (gotEvent)
DoEvent(&theEvent);
DSSyncWindowsWithFiles(kDontForceSynchronization);
}